From: Matthew Vernon
PCRE2_CONFIG_JITTARGET
-The where argument should point to a buffer that is at least 64 code
-units long. (The exact length required can be found by calling
-pcre2_config() with where set to NULL.) The buffer is filled with a
-string that contains the name of the architecture for which the JIT compiler is
-configured, for example "x86 32bit (little endian + unaligned)". If JIT support
-is not available, PCRE2_ERROR_BADOPTION is returned, otherwise the number of
-code units used is returned. This is the length of the string, plus one unit
-for the terminating zero.
+The where argument should point to a code-unit-aligned buffer. All
+previous versions of PCRE2 have required no more than 128 code units of buffer
+capacity. However, this requirement is not guaranteed to be maintained, so
+applications should call pcre2_config() with where set to NULL to
+receive the required buffer size, then assert or allocate a suitably-size buffer
+for a second call to pcre2_config(). The buffer is filled with a string
+that contains the name of the architecture for which the JIT compiler is
+configured at build time, for example, a 64-bit ARM CPU that supports the
+Armv8.1 extension writes "ARM-64 (LSE) 64bit (little endian + unaligned)". If
+JIT support is not available, PCRE2_ERROR_BADOPTION is returned; otherwise the
+number of code units used is returned. This is the length of the string plus one
+unit for the terminating zero.
PCRE2_CONFIG_LINKSIZE
@@ -1450,13 +1454,15 @@ below.
PCRE2_CONFIG_UNICODE_VERSION
-The where argument should point to a buffer that is at least 24 code
-units long. (The exact length required can be found by calling
-pcre2_config() with where set to NULL.) If PCRE2 has been compiled
-without Unicode support, the buffer is filled with the text "Unicode not
-supported". Otherwise, the Unicode version string (for example, "8.0.0") is
-inserted. The number of code units used is returned. This is the length of the
-string plus one unit for the terminating zero.
+The where argument should point to a code-unit-aligned buffer. All
+previous versions of PCRE2 have required no more than 24 code units of buffer
+capacity. However, applications should call pcre2_config() with
+where set to NULL to receive the required buffer size, then assert or
+allocate a suitably-size buffer for a second call to pcre2_config(). If
+PCRE2 has been compiled without Unicode support, the buffer is filled with the
+text "Unicode not supported". Otherwise, the Unicode version string (for
+example, "8.0.0") is written. The number of code units used is returned. This is
+the length of the string plus one unit for the terminating zero.
PCRE2_CONFIG_UNICODE
@@ -1465,12 +1471,14 @@ available; otherwise it is set to zero. Unicode support implies UTF support.
PCRE2_CONFIG_VERSION
-The where argument should point to a buffer that is at least 24 code
-units long. (The exact length required can be found by calling
-pcre2_config() with where set to NULL.) The buffer is filled with
-the PCRE2 version string, zero-terminated. The number of code units used is
-returned. This is the length of the string plus one unit for the terminating
-zero.
+The where argument should point to a code-unit-aligned buffer. All
+previous versions of PCRE2 have required no more than 24 code units of buffer
+capacity. However, applications should call pcre2_config() with
+where set to NULL to receive the required buffer size, then assert or
+allocate a suitably-size buffer for a second call to pcre2_config(). The
+buffer is filled with the PCRE2 version string, zero-terminated. The number of
+code units used is returned. This is the length of the string plus one unit for
+the terminating zero.
@@ -3526,7 +3534,7 @@ A common task for applications is to implement "global" matching behaviour, for example, replacing all matches in the subject; splitting the subject on all matches; or simply counting the number of matches. The pcre2_next_match() function helps with this task by providing the appropriate parameters for the -next match attempt (available since PCRE2 10.46). +next match attempt (available since PCRE2 10.47).
First, a match attempt should be made using one of the matching functions @@ -3917,6 +3925,15 @@ output buffer. Substitution callouts (see can be used to separate them if necessary.
+Partial matching is supported, with limitations: if matching succeeds but with a +partial match, then pcre2_substitute returns PCRE2_ERROR_PARTIAL. When +partial-matching (either of PCRE2_PARTIAL_HARD or PCRE2_PARTIAL_SOFT is passed), +then PCRE2_SUBSTITUTE_REPLACEMENT_ONLY must also be set, or else +PCRE2_ERROR_BADOPTION is returned. Similarly, certain replacement items +($' and $_) cause PCRE2_ERROR_PARTIALSUBS to be returned when partial-matching, +even if a complete match is found. +
+The outlengthptr argument of pcre2_substitute() must point to a variable that contains the length, in code units, of the output buffer. If the function is successful, the value is updated to contain the length in code @@ -4623,7 +4640,7 @@ Cambridge, England.
-Last updated: 19 October 2025
+Last updated: 08 December 2025
Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2jit.html b/doc/html/pcre2jit.html
index cc26cc0..c3f18f4 100644
--- a/doc/html/pcre2jit.html
+++ b/doc/html/pcre2jit.html
@@ -460,10 +460,11 @@ processed by pcre2_jit_compile()).
The fast path function is called pcre2_jit_match(), and it takes exactly
the same arguments as pcre2_match(). However, the subject string must be
specified with a length; PCRE2_ZERO_TERMINATED is not supported. Unsupported
-option bits (for example, PCRE2_ANCHORED and PCRE2_ENDANCHORED) are ignored, as
-is the PCRE2_NO_JIT option. The return values are also the same as for
-pcre2_match(), plus PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial
-or complete) is requested that was not compiled.
+option bits (for example, PCRE2_ANCHORED, PCRE2_ENDANCHORED, and
+PCRE2_COPY_MATCHED_SUBJECT) are ignored, as is the PCRE2_NO_JIT option. The
+return values are also the same as for pcre2_match(), plus
+PCRE2_ERROR_JIT_BADOPTION if a matching mode (partial or complete) is requested
+that was not compiled.
When you call pcre2_match(), as well as testing for invalid options, a @@ -496,7 +497,7 @@ Cambridge, England.
-Last updated: 22 August 2024
+Last updated: 08 August 2026
Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2partial.html b/doc/html/pcre2partial.html
index 529cc7b..acce666 100644
--- a/doc/html/pcre2partial.html
+++ b/doc/html/pcre2partial.html
@@ -388,6 +388,20 @@ two buffers. If a partial match at offset n in the first buffer is
followed by "no match" when PCRE2_DFA_RESTART is used on the second buffer, you
can then try a new match starting at offset n+1 in the first buffer.
+Therefore, PCRE2_DFA_RESTART does not remove the need to keep earlier subject +data. In order to perform a bumpalong and continue matching at the next +character, all subject data from the current match start must be retained, +together with enough preceding data to satisfy the requirements of lookbehind +assertions (remembering as above that PCRE2_INFO_MAXLOOKBEHIND only describes +the buffer requirement of a single lookbehind, and nested lookbehinds can read +back further from the match start). This makes streaming match processing +using PCRE2_DFA_RESTART challenging, and the application cannot easily set a +bound on the number of chunks to buffer. For multi-segment searching that is +intended to produce the same result as searching the whole subject, it is +usually simpler to avoid PCRE2_DFA_RESTART and run a fresh match, using either +matching function, over the retained text. +
Philip Hazel @@ -399,7 +413,7 @@ Cambridge, England.
-Last updated: 27 November 2024
+Last updated: 16 August 2026
Copyright © 1997-2019 University of Cambridge.
diff --git a/doc/html/pcre2pattern.html b/doc/html/pcre2pattern.html
index a18a297..9ff064e 100644
--- a/doc/html/pcre2pattern.html
+++ b/doc/html/pcre2pattern.html
@@ -3451,7 +3451,7 @@ below.
Recursion and subroutines with returned capture groups
-Since PCRE2 10.46, recursion and subroutine calls may also specify a list of +Since PCRE2 10.47, recursion and subroutine calls may also specify a list of capture groups to return. This is a PCRE2 syntax extension not supported by Perl. The pattern matching recurses into the referenced expression as described above, however, when the recursion returns to the calling expression the @@ -4183,7 +4183,7 @@ Cambridge, England.
-Last updated: 03 September 2025
+Last updated: 25 October 2025
Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index cc9136a..208d660 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -214,9 +214,11 @@ If an unknown option is given, an error message is output; the exit code is 0.
--colo[u]r[=<always,auto,never>] -By default, the output is coloured if the output file is a terminal (auto). -Force or suppress output of ANSI colour escapes with always and never -respectively. +With auto, the output is coloured if the output is to a terminal. Force or +suppress output of ANSI colour escapes with always (or no specifier +provided) and never respectively. If no colour option is provided, the +default is auto, unless the NO_COLOR environment variable is defined and +non-empty.
-d @@ -861,7 +863,7 @@ when it can never be used. The framesize modifier shows the size, in bytes, of each storage frame used by pcre2_match() for handling backtracking. The size depends on the number of capturing parentheses in the pattern. A vector of these frames is -used at matching time; its overall size is shown when the heaframes_size +used at matching time; its overall size is shown when the heapframes_size subject modifier is set.
@@ -2303,7 +2305,7 @@ Cambridge, England.
-Last updated: 12 October 2025
+Last updated: 22 August 2026
Copyright © 1997-2024 University of Cambridge.
diff --git a/doc/pcre2-config.1 b/doc/pcre2-config.1
index c119a11..e72663f 100644
--- a/doc/pcre2-config.1
+++ b/doc/pcre2-config.1
@@ -1,4 +1,4 @@
-.TH PCRE2-CONFIG 1 "22 February 2025" "PCRE2 10.47"
+.TH PCRE2-CONFIG 1 "22 February 2025" "PCRE2 10.48-RC1"
.SH NAME
pcre2-config - program to return PCRE2 configuration
.SH SYNOPSIS
diff --git a/doc/pcre2-config.txt b/doc/pcre2-config.txt
index 74592eb..c134a6a 100644
--- a/doc/pcre2-config.txt
+++ b/doc/pcre2-config.txt
@@ -81,4 +81,4 @@ REVISION
Last updated: 22 February 2025
-PCRE2 10.47 22 February 2025 PCRE2-CONFIG(1)
+PCRE2 10.48-RC1 22 February 2025 PCRE2-CONFIG(1)
diff --git a/doc/pcre2.3 b/doc/pcre2.3
index 1c3d9d2..0698b67 100644
--- a/doc/pcre2.3
+++ b/doc/pcre2.3
@@ -1,4 +1,4 @@
-.TH PCRE2 3 "22 February 2025" "PCRE2 10.47"
+.TH PCRE2 3 "22 February 2025" "PCRE2 10.48-RC1"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH INTRODUCTION
diff --git a/doc/pcre2.txt b/doc/pcre2.txt
index b0b564c..f934cd2 100644
--- a/doc/pcre2.txt
+++ b/doc/pcre2.txt
@@ -189,7 +189,7 @@ REVISION
Copyright (c) 1997-2021 University of Cambridge.
-PCRE2 10.47 22 February 2025 PCRE2(3)
+PCRE2 10.48-RC1 22 February 2025 PCRE2(3)
------------------------------------------------------------------------------
@@ -1364,14 +1364,19 @@ CHECKING BUILD-TIME OPTIONS
PCRE2_CONFIG_JITTARGET
- The where argument should point to a buffer that is at least 64 code
- units long. (The exact length required can be found by calling
- pcre2_config() with where set to NULL.) The buffer is filled with a
- string that contains the name of the architecture for which the JIT
- compiler is configured, for example "x86 32bit (little endian + un-
- aligned)". If JIT support is not available, PCRE2_ERROR_BADOPTION is
- returned, otherwise the number of code units used is returned. This is
- the length of the string, plus one unit for the terminating zero.
+ The where argument should point to a code-unit-aligned buffer. All pre-
+ vious versions of PCRE2 have required no more than 128 code units of
+ buffer capacity. However, this requirement is not guaranteed to be
+ maintained, so applications should call pcre2_config() with where set
+ to NULL to receive the required buffer size, then assert or allocate a
+ suitably-size buffer for a second call to pcre2_config(). The buffer is
+ filled with a string that contains the name of the architecture for
+ which the JIT compiler is configured at build time, for example, a
+ 64-bit ARM CPU that supports the Armv8.1 extension writes "ARM-64 (LSE)
+ 64bit (little endian + unaligned)". If JIT support is not available,
+ PCRE2_ERROR_BADOPTION is returned; otherwise the number of code units
+ used is returned. This is the length of the string plus one unit for
+ the terminating zero.
PCRE2_CONFIG_LINKSIZE
@@ -1441,13 +1446,16 @@ CHECKING BUILD-TIME OPTIONS
PCRE2_CONFIG_UNICODE_VERSION
- The where argument should point to a buffer that is at least 24 code
- units long. (The exact length required can be found by calling
- pcre2_config() with where set to NULL.) If PCRE2 has been compiled
- without Unicode support, the buffer is filled with the text "Unicode
- not supported". Otherwise, the Unicode version string (for example,
- "8.0.0") is inserted. The number of code units used is returned. This
- is the length of the string plus one unit for the terminating zero.
+ The where argument should point to a code-unit-aligned buffer. All pre-
+ vious versions of PCRE2 have required no more than 24 code units of
+ buffer capacity. However, applications should call pcre2_config() with
+ where set to NULL to receive the required buffer size, then assert or
+ allocate a suitably-size buffer for a second call to pcre2_config(). If
+ PCRE2 has been compiled without Unicode support, the buffer is filled
+ with the text "Unicode not supported". Otherwise, the Unicode version
+ string (for example, "8.0.0") is written. The number of code units used
+ is returned. This is the length of the string plus one unit for the
+ terminating zero.
PCRE2_CONFIG_UNICODE
@@ -1457,12 +1465,14 @@ CHECKING BUILD-TIME OPTIONS
PCRE2_CONFIG_VERSION
- The where argument should point to a buffer that is at least 24 code
- units long. (The exact length required can be found by calling
- pcre2_config() with where set to NULL.) The buffer is filled with the
- PCRE2 version string, zero-terminated. The number of code units used is
- returned. This is the length of the string plus one unit for the termi-
- nating zero.
+ The where argument should point to a code-unit-aligned buffer. All pre-
+ vious versions of PCRE2 have required no more than 24 code units of
+ buffer capacity. However, applications should call pcre2_config() with
+ where set to NULL to receive the required buffer size, then assert or
+ allocate a suitably-size buffer for a second call to pcre2_config().
+ The buffer is filled with the PCRE2 version string, zero-terminated.
+ The number of code units used is returned. This is the length of the
+ string plus one unit for the terminating zero.
COMPILING A PATTERN
@@ -1477,107 +1487,107 @@ COMPILING A PATTERN
pcre2_code *pcre2_code_copy_with_tables(const pcre2_code *code);
- The pcre2_compile() function compiles a pattern into an internal form.
- The pattern is defined by a pointer to a string of code units and a
+ The pcre2_compile() function compiles a pattern into an internal form.
+ The pattern is defined by a pointer to a string of code units and a
length in code units. If the pattern is zero-terminated, the length can
- be specified as PCRE2_ZERO_TERMINATED. A NULL pattern pointer with a
- length of zero is treated as an empty string (NULL with a non-zero
- length causes an error return). The function returns a pointer to a
+ be specified as PCRE2_ZERO_TERMINATED. A NULL pattern pointer with a
+ length of zero is treated as an empty string (NULL with a non-zero
+ length causes an error return). The function returns a pointer to a
block of memory that contains the compiled pattern and related data, or
NULL if an error occurred.
- If the compile context argument ccontext is NULL, memory for the com-
- piled pattern is obtained by calling malloc(). Otherwise, it is ob-
+ If the compile context argument ccontext is NULL, memory for the com-
+ piled pattern is obtained by calling malloc(). Otherwise, it is ob-
tained from the same memory function that was used for the compile con-
text. The caller must free the memory by calling pcre2_code_free() when
it is no longer needed. If pcre2_code_free() is called with a NULL ar-
gument, it returns immediately, without doing anything.
The function pcre2_code_copy() makes a copy of the compiled code in new
- memory, using the same memory allocator as was used for the original.
- However, if the code has been processed by the JIT compiler (see be-
- low), the JIT information cannot be copied (because it is position-de-
- pendent). The new copy can initially be used only for non-JIT match-
- ing, though it can be passed to pcre2_jit_compile() if required. If
+ memory, using the same memory allocator as was used for the original.
+ However, if the code has been processed by the JIT compiler (see be-
+ low), the JIT information cannot be copied (because it is position-de-
+ pendent). The new copy can initially be used only for non-JIT match-
+ ing, though it can be passed to pcre2_jit_compile() if required. If
pcre2_code_copy() is called with a NULL argument, it returns NULL.
The pcre2_code_copy() function provides a way for individual threads in
- a multithreaded application to acquire a private copy of shared com-
- piled code. However, it does not make a copy of the character tables
- used by the compiled pattern; the new pattern code points to the same
- tables as the original code. (See "Locale Support" below for details
- of these character tables.) In many applications the same tables are
- used throughout, so this behaviour is appropriate. Nevertheless, there
+ a multithreaded application to acquire a private copy of shared com-
+ piled code. However, it does not make a copy of the character tables
+ used by the compiled pattern; the new pattern code points to the same
+ tables as the original code. (See "Locale Support" below for details
+ of these character tables.) In many applications the same tables are
+ used throughout, so this behaviour is appropriate. Nevertheless, there
are occasions when a copy of a compiled pattern and the relevant tables
- are needed. The pcre2_code_copy_with_tables() provides this facility.
- Copies of both the code and the tables are made, with the new code
- pointing to the new tables. The memory for the new tables is automati-
- cally freed when pcre2_code_free() is called for the new copy of the
- compiled code. If pcre2_code_copy_with_tables() is called with a NULL
+ are needed. The pcre2_code_copy_with_tables() provides this facility.
+ Copies of both the code and the tables are made, with the new code
+ pointing to the new tables. The memory for the new tables is automati-
+ cally freed when pcre2_code_free() is called for the new copy of the
+ compiled code. If pcre2_code_copy_with_tables() is called with a NULL
argument, it returns NULL.
- NOTE: When one of the matching functions is called, pointers to the
+ NOTE: When one of the matching functions is called, pointers to the
compiled pattern and the subject string are set in the match data block
- so that they can be referenced by the substring extraction functions
- after a successful match. After running a match, you must not free a
- compiled pattern or a subject string until after all operations on the
- match data block have taken place, unless, in the case of the subject
- string, you have used the PCRE2_COPY_MATCHED_SUBJECT option, which is
- described in the section entitled "Option bits for pcre2_match()" be-
+ so that they can be referenced by the substring extraction functions
+ after a successful match. After running a match, you must not free a
+ compiled pattern or a subject string until after all operations on the
+ match data block have taken place, unless, in the case of the subject
+ string, you have used the PCRE2_COPY_MATCHED_SUBJECT option, which is
+ described in the section entitled "Option bits for pcre2_match()" be-
low.
- The options argument for pcre2_compile() contains various bit settings
- that affect the compilation. It should be zero if none of them are re-
- quired. The available options are described below. Some of them (in
- particular, those that are compatible with Perl, but some others as
- well) can also be set and unset from within the pattern (see the de-
+ The options argument for pcre2_compile() contains various bit settings
+ that affect the compilation. It should be zero if none of them are re-
+ quired. The available options are described below. Some of them (in
+ particular, those that are compatible with Perl, but some others as
+ well) can also be set and unset from within the pattern (see the de-
tailed description in the pcre2pattern documentation).
- For those options that can be different in different parts of the pat-
- tern, the contents of the options argument specifies their settings at
- the start of compilation. The PCRE2_ANCHORED, PCRE2_ENDANCHORED, and
- PCRE2_NO_UTF_CHECK options can be set at the time of matching as well
+ For those options that can be different in different parts of the pat-
+ tern, the contents of the options argument specifies their settings at
+ the start of compilation. The PCRE2_ANCHORED, PCRE2_ENDANCHORED, and
+ PCRE2_NO_UTF_CHECK options can be set at the time of matching as well
as at compile time.
Some additional options and less frequently required compile-time para-
- meters (for example, the newline setting) can be provided in a compile
+ meters (for example, the newline setting) can be provided in a compile
context (as described above).
If errorcode or erroroffset is NULL, pcre2_compile() returns NULL imme-
- diately. Otherwise, the variables to which these point are set to an
+ diately. Otherwise, the variables to which these point are set to an
error code and an offset (number of code units) within the pattern, re-
spectively, when pcre2_compile() returns NULL because a compilation er-
ror has occurred.
There are over 100 positive error codes that pcre2_compile() may return
if it finds an error in the pattern. There are also some negative error
- codes that are used for invalid UTF strings when validity checking is
- in force. These are the same as given by pcre2_match() and
+ codes that are used for invalid UTF strings when validity checking is
+ in force. These are the same as given by pcre2_match() and
pcre2_dfa_match(), and are described in the pcre2unicode documentation.
- There is no separate documentation for the positive error codes, be-
- cause the textual error messages that are obtained by calling the
+ There is no separate documentation for the positive error codes, be-
+ cause the textual error messages that are obtained by calling the
pcre2_get_error_message() function (see "Obtaining a textual error mes-
- sage" below) should be self-explanatory. Macro names starting with
- PCRE2_ERROR_ are defined for both positive and negative error codes in
- pcre2.h. When compilation is successful errorcode is set to a value
- that returns the message "no error" if passed to pcre2_get_error_mes-
+ sage" below) should be self-explanatory. Macro names starting with
+ PCRE2_ERROR_ are defined for both positive and negative error codes in
+ pcre2.h. When compilation is successful errorcode is set to a value
+ that returns the message "no error" if passed to pcre2_get_error_mes-
sage().
The value returned in erroroffset is an indication of where in the pat-
- tern an error occurred. When there is no error, zero is returned. A
- non-zero value is not necessarily the furthest point in the pattern
- that was read. For example, after the error "lookbehind assertion is
- not fixed length", the error offset points to the start of the failing
+ tern an error occurred. When there is no error, zero is returned. A
+ non-zero value is not necessarily the furthest point in the pattern
+ that was read. For example, after the error "lookbehind assertion is
+ not fixed length", the error offset points to the start of the failing
assertion. For an invalid UTF-8 or UTF-16 string, the offset is that of
the first code unit of the failing character.
- Some errors are not detected until the whole pattern has been scanned;
- in these cases, the offset passed back is the length of the pattern.
- Note that the offset is in code units, not characters, even in a UTF
+ Some errors are not detected until the whole pattern has been scanned;
+ in these cases, the offset passed back is the length of the pattern.
+ Note that the offset is in code units, not characters, even in a UTF
mode. It may sometimes point into the middle of a UTF-8 or UTF-16 char-
acter.
- This code fragment shows a typical straightforward call to pcre2_com-
+ This code fragment shows a typical straightforward call to pcre2_com-
pile():
pcre2_code *re;
@@ -1594,471 +1604,471 @@ COMPILING A PATTERN
Main compile options
- The following names for option bits are defined in the pcre2.h header
+ The following names for option bits are defined in the pcre2.h header
file:
PCRE2_ANCHORED
If this bit is set, the pattern is forced to be "anchored", that is, it
- is constrained to match only at the first matching point in the string
- that is being searched (the "subject string"). This effect can also be
- achieved by appropriate constructs in the pattern itself, which is the
+ is constrained to match only at the first matching point in the string
+ that is being searched (the "subject string"). This effect can also be
+ achieved by appropriate constructs in the pattern itself, which is the
only way to do it in Perl.
PCRE2_ALLOW_EMPTY_CLASS
- By default, for compatibility with Perl, a closing square bracket that
- immediately follows an opening one is treated as a data character for
- the class. When PCRE2_ALLOW_EMPTY_CLASS is set, it terminates the
+ By default, for compatibility with Perl, a closing square bracket that
+ immediately follows an opening one is treated as a data character for
+ the class. When PCRE2_ALLOW_EMPTY_CLASS is set, it terminates the
class, which therefore contains no characters and so can never match.
PCRE2_ALT_BSUX
- This option request alternative handling of three escape sequences,
- which makes PCRE2's behaviour more like ECMAscript (aka JavaScript).
+ This option request alternative handling of three escape sequences,
+ which makes PCRE2's behaviour more like ECMAscript (aka JavaScript).
When it is set:
(1) \U matches an upper case "U" character; by default \U causes a com-
pile time error (Perl uses \U to upper case subsequent characters).
(2) \u matches a lower case "u" character unless it is followed by four
- hexadecimal digits, in which case the hexadecimal number defines the
- code point to match. By default, \u causes a compile time error (Perl
+ hexadecimal digits, in which case the hexadecimal number defines the
+ code point to match. By default, \u causes a compile time error (Perl
uses it to upper case the following character).
- (3) \x matches a lower case "x" character unless it is followed by two
- hexadecimal digits, in which case the hexadecimal number defines the
- code point to match. By default, as in Perl, a hexadecimal number is
+ (3) \x matches a lower case "x" character unless it is followed by two
+ hexadecimal digits, in which case the hexadecimal number defines the
+ code point to match. By default, as in Perl, a hexadecimal number is
always expected after \x, but it may have one or two digits.
ECMAscript 6 added additional functionality to \u. This can be accessed
- using the PCRE2_EXTRA_ALT_BSUX extra option (see "Extra compile op-
+ using the PCRE2_EXTRA_ALT_BSUX extra option (see "Extra compile op-
tions" below). Note that this alternative escape handling applies only
- to patterns. Neither of these options affects the processing of re-
+ to patterns. Neither of these options affects the processing of re-
placement strings passed to pcre2_substitute().
PCRE2_ALT_CIRCUMFLEX
In multiline mode (when PCRE2_MULTILINE is set), the circumflex
- metacharacter matches at the start of the subject (unless PCRE2_NOTBOL
- is set), and also after any internal newline. However, it does not
+ metacharacter matches at the start of the subject (unless PCRE2_NOTBOL
+ is set), and also after any internal newline. However, it does not
match after a newline at the end of the subject, for compatibility with
- Perl. If you want a multiline circumflex also to match after a termi-
+ Perl. If you want a multiline circumflex also to match after a termi-
nating newline, you must set PCRE2_ALT_CIRCUMFLEX.
PCRE2_ALT_EXTENDED_CLASS
- Alters the parsing of character classes to follow the extended syntax
+ Alters the parsing of character classes to follow the extended syntax
described by Unicode UTS#18. The PCRE2_ALT_EXTENDED_CLASS option has no
- impact on the behaviour of the Perl-specific "(?[...])" syntax for ex-
- tended classes, but instead enables the alternative syntax of extended
- class behaviour inside ordinary "[...]" character classes. See the
- pcre2pattern documentation for details of the character classes sup-
+ impact on the behaviour of the Perl-specific "(?[...])" syntax for ex-
+ tended classes, but instead enables the alternative syntax of extended
+ class behaviour inside ordinary "[...]" character classes. See the
+ pcre2pattern documentation for details of the character classes sup-
ported.
PCRE2_ALT_VERBNAMES
- By default, for compatibility with Perl, the name in any verb sequence
- such as (*MARK:NAME) is any sequence of characters that does not in-
- clude a closing parenthesis. The name is not processed in any way, and
- it is not possible to include a closing parenthesis in the name. How-
- ever, if the PCRE2_ALT_VERBNAMES option is set, normal backslash pro-
- cessing is applied to verb names and only an unescaped closing paren-
- thesis terminates the name. A closing parenthesis can be included in a
- name either as \) or between \Q and \E. If the PCRE2_EXTENDED or
- PCRE2_EXTENDED_MORE option is set with PCRE2_ALT_VERBNAMES, unescaped
+ By default, for compatibility with Perl, the name in any verb sequence
+ such as (*MARK:NAME) is any sequence of characters that does not in-
+ clude a closing parenthesis. The name is not processed in any way, and
+ it is not possible to include a closing parenthesis in the name. How-
+ ever, if the PCRE2_ALT_VERBNAMES option is set, normal backslash pro-
+ cessing is applied to verb names and only an unescaped closing paren-
+ thesis terminates the name. A closing parenthesis can be included in a
+ name either as \) or between \Q and \E. If the PCRE2_EXTENDED or
+ PCRE2_EXTENDED_MORE option is set with PCRE2_ALT_VERBNAMES, unescaped
white space in verb names is skipped and #-comments are recognized, ex-
actly as in the rest of the pattern.
PCRE2_AUTO_CALLOUT
- If this bit is set, pcre2_compile() automatically inserts callout
- items, all with number 255, before each pattern item, except immedi-
- ately before or after an explicit callout in the pattern. For discus-
+ If this bit is set, pcre2_compile() automatically inserts callout
+ items, all with number 255, before each pattern item, except immedi-
+ ately before or after an explicit callout in the pattern. For discus-
sion of the callout facility, see the pcre2callout documentation.
PCRE2_CASELESS
- If this bit is set, letters in the pattern match both upper and lower
- case letters in the subject. It is equivalent to Perl's /i option, and
- it can be changed within a pattern by a (?i) option setting. If either
- PCRE2_UTF or PCRE2_UCP is set, Unicode properties are used for all
- characters with more than one other case, and for all characters whose
+ If this bit is set, letters in the pattern match both upper and lower
+ case letters in the subject. It is equivalent to Perl's /i option, and
+ it can be changed within a pattern by a (?i) option setting. If either
+ PCRE2_UTF or PCRE2_UCP is set, Unicode properties are used for all
+ characters with more than one other case, and for all characters whose
code points are greater than U+007F.
Note that there are two ASCII characters, K and S, that, in addition to
- their lower case ASCII equivalents, are case-equivalent with U+212A
+ their lower case ASCII equivalents, are case-equivalent with U+212A
(Kelvin sign) and U+017F (long S) respectively. If you do not want this
- case equivalence, you can suppress it by setting PCRE2_EXTRA_CASE-
+ case equivalence, you can suppress it by setting PCRE2_EXTRA_CASE-
LESS_RESTRICT.
- One language family, Turkish and Azeri, has its own case-insensitivity
- rules, which can be selected by setting PCRE2_EXTRA_TURKISH_CASING.
- This alters the behaviour of the 'i', 'I', U+0130 (capital I with dot
+ One language family, Turkish and Azeri, has its own case-insensitivity
+ rules, which can be selected by setting PCRE2_EXTRA_TURKISH_CASING.
+ This alters the behaviour of the 'i', 'I', U+0130 (capital I with dot
above), and U+0131 (small dotless i) characters.
For lower valued characters with only one other case, a lookup table is
- used for speed. When neither PCRE2_UTF nor PCRE2_UCP is set, a lookup
+ used for speed. When neither PCRE2_UTF nor PCRE2_UCP is set, a lookup
table is used for all code points less than 256, and higher code points
(available only in 16-bit or 32-bit mode) are treated as not having an-
other case.
From release 10.45 PCRE2_CASELESS also affects what some of the letter-
- related Unicode property escapes (\p and \P) match. The properties Lu
+ related Unicode property escapes (\p and \P) match. The properties Lu
(upper case letter), Ll (lower case letter), and Lt (title case letter)
are all treated as LC (cased letter) when PCRE2_CASELESS is set.
PCRE2_DOLLAR_ENDONLY
- If this bit is set, a dollar metacharacter in the pattern matches only
- at the end of the subject string. Without this option, a dollar also
- matches immediately before a newline at the end of the string (but not
- before any other newlines). The PCRE2_DOLLAR_ENDONLY option is ignored
- if PCRE2_MULTILINE is set. There is no equivalent to this option in
+ If this bit is set, a dollar metacharacter in the pattern matches only
+ at the end of the subject string. Without this option, a dollar also
+ matches immediately before a newline at the end of the string (but not
+ before any other newlines). The PCRE2_DOLLAR_ENDONLY option is ignored
+ if PCRE2_MULTILINE is set. There is no equivalent to this option in
Perl, and no way to set it within a pattern.
PCRE2_DOTALL
- If this bit is set, a dot metacharacter in the pattern matches any
- character, including one that indicates a newline. However, it only
+ If this bit is set, a dot metacharacter in the pattern matches any
+ character, including one that indicates a newline. However, it only
ever matches one character, even if newlines are coded as CRLF. Without
this option, a dot does not match when the current position in the sub-
- ject is at a newline. This option is equivalent to Perl's /s option,
+ ject is at a newline. This option is equivalent to Perl's /s option,
and it can be changed within a pattern by a (?s) option setting. A neg-
- ative class such as [^a] always matches newline characters, and the \N
- escape sequence always matches a non-newline character, independent of
+ ative class such as [^a] always matches newline characters, and the \N
+ escape sequence always matches a non-newline character, independent of
the setting of PCRE2_DOTALL.
PCRE2_DUPNAMES
- If this bit is set, names used to identify capture groups need not be
- unique. This can be helpful for certain types of pattern when it is
- known that only one instance of the named group can ever be matched.
- There are more details of named capture groups below; see also the
+ If this bit is set, names used to identify capture groups need not be
+ unique. This can be helpful for certain types of pattern when it is
+ known that only one instance of the named group can ever be matched.
+ There are more details of named capture groups below; see also the
pcre2pattern documentation.
PCRE2_ENDANCHORED
- If this bit is set, the end of any pattern match must be right at the
+ If this bit is set, the end of any pattern match must be right at the
end of the string being searched (the "subject string"). If the pattern
match succeeds by reaching (*ACCEPT), but does not reach the end of the
- subject, the match fails at the current starting point. For unanchored
- patterns, a new match is then tried at the next starting point. How-
+ subject, the match fails at the current starting point. For unanchored
+ patterns, a new match is then tried at the next starting point. How-
ever, if the match succeeds by reaching the end of the pattern, but not
- the end of the subject, backtracking occurs and an alternative match
+ the end of the subject, backtracking occurs and an alternative match
may be found. Consider these two patterns:
.(*ACCEPT)|..
.|..
- If matched against "abc" with PCRE2_ENDANCHORED set, the first matches
- "c" whereas the second matches "bc". The effect of PCRE2_ENDANCHORED
- can also be achieved by appropriate constructs in the pattern itself,
+ If matched against "abc" with PCRE2_ENDANCHORED set, the first matches
+ "c" whereas the second matches "bc". The effect of PCRE2_ENDANCHORED
+ can also be achieved by appropriate constructs in the pattern itself,
which is the only way to do it in Perl.
For DFA matching with pcre2_dfa_match(), PCRE2_ENDANCHORED applies only
- to the first (that is, the longest) matched string. Other parallel
- matches, which are necessarily substrings of the first one, must obvi-
+ to the first (that is, the longest) matched string. Other parallel
+ matches, which are necessarily substrings of the first one, must obvi-
ously end before the end of the subject.
PCRE2_EXTENDED
- If this bit is set, most white space characters in the pattern are to-
- tally ignored except when escaped, inside a character class, or inside
- a \Q...\E sequence. However, white space is not allowed within se-
- quences such as (?> that introduce various parenthesized groups, nor
- within numerical quantifiers such as {1,3}. Ignorable white space is
- permitted between an item and a following quantifier and between a
- quantifier and a following + that indicates possessiveness. PCRE2_EX-
- TENDED is equivalent to Perl's /x option, and it can be changed within
+ If this bit is set, most white space characters in the pattern are to-
+ tally ignored except when escaped, inside a character class, or inside
+ a \Q...\E sequence. However, white space is not allowed within se-
+ quences such as (?> that introduce various parenthesized groups, nor
+ within numerical quantifiers such as {1,3}. Ignorable white space is
+ permitted between an item and a following quantifier and between a
+ quantifier and a following + that indicates possessiveness. PCRE2_EX-
+ TENDED is equivalent to Perl's /x option, and it can be changed within
a pattern by a (?x) option setting.
- When PCRE2 is compiled without Unicode support, PCRE2_EXTENDED recog-
- nizes as white space only those characters with code points less than
+ When PCRE2 is compiled without Unicode support, PCRE2_EXTENDED recog-
+ nizes as white space only those characters with code points less than
256 that are flagged as white space in its low-character table. The ta-
ble is normally created by pcre2_maketables(), which uses the isspace()
- function to identify space characters. In most ASCII environments, the
- relevant characters are those with code points 0x0009 (tab), 0x000A
- (linefeed), 0x000B (vertical tab), 0x000C (formfeed), 0x000D (carriage
+ function to identify space characters. In most ASCII environments, the
+ relevant characters are those with code points 0x0009 (tab), 0x000A
+ (linefeed), 0x000B (vertical tab), 0x000C (formfeed), 0x000D (carriage
return), and 0x0020 (space).
When PCRE2 is compiled with Unicode support, in addition to these char-
- acters, five more Unicode "Pattern White Space" characters are recog-
+ acters, five more Unicode "Pattern White Space" characters are recog-
nized by PCRE2_EXTENDED. These are U+0085 (next line), U+200E (left-to-
- right mark), U+200F (right-to-left mark), U+2028 (line separator), and
- U+2029 (paragraph separator). This set of characters is the same as
- recognized by Perl's /x option. Note that the horizontal and vertical
- space characters that are matched by the \h and \v escapes in patterns
+ right mark), U+200F (right-to-left mark), U+2028 (line separator), and
+ U+2029 (paragraph separator). This set of characters is the same as
+ recognized by Perl's /x option. Note that the horizontal and vertical
+ space characters that are matched by the \h and \v escapes in patterns
are a much bigger set.
- As well as ignoring most white space, PCRE2_EXTENDED also causes char-
- acters between an unescaped # outside a character class and the next
- newline, inclusive, to be ignored, which makes it possible to include
+ As well as ignoring most white space, PCRE2_EXTENDED also causes char-
+ acters between an unescaped # outside a character class and the next
+ newline, inclusive, to be ignored, which makes it possible to include
comments inside complicated patterns. Note that the end of this type of
- comment is a literal newline sequence in the pattern; escape sequences
+ comment is a literal newline sequence in the pattern; escape sequences
that happen to represent a newline do not count.
Which characters are interpreted as newlines can be specified by a set-
- ting in the compile context that is passed to pcre2_compile() or by a
- special sequence at the start of the pattern, as described in the sec-
- tion entitled "Newline conventions" in the pcre2pattern documentation.
+ ting in the compile context that is passed to pcre2_compile() or by a
+ special sequence at the start of the pattern, as described in the sec-
+ tion entitled "Newline conventions" in the pcre2pattern documentation.
A default is defined when PCRE2 is built.
PCRE2_EXTENDED_MORE
- This option has the effect of PCRE2_EXTENDED, but, in addition, un-
- escaped space and horizontal tab characters are ignored inside a char-
- acter class. Note: only these two characters are ignored, not the full
- set of pattern white space characters that are ignored outside a char-
- acter class. PCRE2_EXTENDED_MORE is equivalent to Perl's /xx option,
+ This option has the effect of PCRE2_EXTENDED, but, in addition, un-
+ escaped space and horizontal tab characters are ignored inside a char-
+ acter class. Note: only these two characters are ignored, not the full
+ set of pattern white space characters that are ignored outside a char-
+ acter class. PCRE2_EXTENDED_MORE is equivalent to Perl's /xx option,
and it can be changed within a pattern by a (?xx) option setting.
PCRE2_FIRSTLINE
If this option is set, the start of an unanchored pattern match must be
- before or at the first newline in the subject string following the
- start of matching, though the matched text may continue over the new-
+ before or at the first newline in the subject string following the
+ start of matching, though the matched text may continue over the new-
line. If startoffset is non-zero, the limiting newline is not necessar-
- ily the first newline in the subject. For example, if the subject
+ ily the first newline in the subject. For example, if the subject
string is "abc\nxyz" (where \n represents a single-character newline) a
- pattern match for "yz" succeeds with PCRE2_FIRSTLINE if startoffset is
- greater than 3. See also PCRE2_USE_OFFSET_LIMIT, which provides a more
- general limiting facility. If PCRE2_FIRSTLINE is set with an offset
- limit, a match must occur in the first line and also within the offset
+ pattern match for "yz" succeeds with PCRE2_FIRSTLINE if startoffset is
+ greater than 3. See also PCRE2_USE_OFFSET_LIMIT, which provides a more
+ general limiting facility. If PCRE2_FIRSTLINE is set with an offset
+ limit, a match must occur in the first line and also within the offset
limit. In other words, whichever limit comes first is used. This option
has no effect for anchored patterns.
PCRE2_LITERAL
If this option is set, all meta-characters in the pattern are disabled,
- and it is treated as a literal string. Matching literal strings with a
+ and it is treated as a literal string. Matching literal strings with a
regular expression engine is not the most efficient way of doing it. If
- you are doing a lot of literal matching and are worried about effi-
+ you are doing a lot of literal matching and are worried about effi-
ciency, you should consider using other approaches. The only other main
options that are allowed with PCRE2_LITERAL are: PCRE2_ANCHORED,
PCRE2_ENDANCHORED, PCRE2_AUTO_CALLOUT, PCRE2_CASELESS, PCRE2_FIRSTLINE,
PCRE2_MATCH_INVALID_UTF, PCRE2_NO_START_OPTIMIZE, PCRE2_NO_UTF_CHECK,
- PCRE2_UTF, and PCRE2_USE_OFFSET_LIMIT. The extra options PCRE2_EX-
+ PCRE2_UTF, and PCRE2_USE_OFFSET_LIMIT. The extra options PCRE2_EX-
TRA_MATCH_LINE and PCRE2_EXTRA_MATCH_WORD are also supported. Any other
options cause an error.
PCRE2_MATCH_INVALID_UTF
- This option forces PCRE2_UTF (see below) and also enables support for
- matching by pcre2_match() in subject strings that contain invalid UTF
- sequences. Note, however, that the 16-bit and 32-bit PCRE2 libraries
- process strings as sequences of uint16_t or uint32_t code points. They
+ This option forces PCRE2_UTF (see below) and also enables support for
+ matching by pcre2_match() in subject strings that contain invalid UTF
+ sequences. Note, however, that the 16-bit and 32-bit PCRE2 libraries
+ process strings as sequences of uint16_t or uint32_t code points. They
cannot find valid UTF sequences within an arbitrary string of bytes un-
- less such sequences are suitably aligned. This facility is not sup-
- ported for DFA matching. For details, see the pcre2unicode documenta-
+ less such sequences are suitably aligned. This facility is not sup-
+ ported for DFA matching. For details, see the pcre2unicode documenta-
tion.
PCRE2_MATCH_UNSET_BACKREF
- If this option is set, a backreference to an unset capture group
- matches an empty string (by default this causes the current matching
+ If this option is set, a backreference to an unset capture group
+ matches an empty string (by default this causes the current matching
alternative to fail). A pattern such as (\1)(a) succeeds when this op-
- tion is set (assuming it can find an "a" in the subject), whereas it
- fails by default, for Perl compatibility. Setting this option makes
+ tion is set (assuming it can find an "a" in the subject), whereas it
+ fails by default, for Perl compatibility. Setting this option makes
PCRE2 behave more like ECMAscript (aka JavaScript).
PCRE2_MULTILINE
- By default, for the purposes of matching "start of line" and "end of
- line", PCRE2 treats the subject string as consisting of a single line
- of characters, even if it actually contains newlines. The "start of
- line" metacharacter (^) matches only at the start of the string, and
- the "end of line" metacharacter ($) matches only at the end of the
- string, or before a terminating newline (except when PCRE2_DOLLAR_EN-
+ By default, for the purposes of matching "start of line" and "end of
+ line", PCRE2 treats the subject string as consisting of a single line
+ of characters, even if it actually contains newlines. The "start of
+ line" metacharacter (^) matches only at the start of the string, and
+ the "end of line" metacharacter ($) matches only at the end of the
+ string, or before a terminating newline (except when PCRE2_DOLLAR_EN-
DONLY is set). Note, however, that unless PCRE2_DOTALL is set, the "any
- character" metacharacter (.) does not match at a newline. This behav-
+ character" metacharacter (.) does not match at a newline. This behav-
iour (for ^, $, and dot) is the same as Perl.
- When PCRE2_MULTILINE it is set, the "start of line" and "end of line"
- constructs match immediately following or immediately before internal
- newlines in the subject string, respectively, as well as at the very
- start and end. This is equivalent to Perl's /m option, and it can be
+ When PCRE2_MULTILINE it is set, the "start of line" and "end of line"
+ constructs match immediately following or immediately before internal
+ newlines in the subject string, respectively, as well as at the very
+ start and end. This is equivalent to Perl's /m option, and it can be
changed within a pattern by a (?m) option setting. Note that the "start
of line" metacharacter does not match after a newline at the end of the
- subject, for compatibility with Perl. However, you can change this by
- setting the PCRE2_ALT_CIRCUMFLEX option. If there are no newlines in a
- subject string, or no occurrences of ^ or $ in a pattern, setting
+ subject, for compatibility with Perl. However, you can change this by
+ setting the PCRE2_ALT_CIRCUMFLEX option. If there are no newlines in a
+ subject string, or no occurrences of ^ or $ in a pattern, setting
PCRE2_MULTILINE has no effect.
PCRE2_NEVER_BACKSLASH_C
- This option locks out the use of \C in the pattern that is being com-
- piled. This escape can cause unpredictable behaviour in UTF-8 or
- UTF-16 modes, because it may leave the current matching point in the
+ This option locks out the use of \C in the pattern that is being com-
+ piled. This escape can cause unpredictable behaviour in UTF-8 or
+ UTF-16 modes, because it may leave the current matching point in the
middle of a multi-code-unit character. This option may be useful in ap-
plications that process patterns from external sources. Note that there
is also a build-time option that permanently locks out the use of \C.
PCRE2_NEVER_UCP
- This option locks out the use of Unicode properties for handling \B,
+ This option locks out the use of Unicode properties for handling \B,
\b, \D, \d, \S, \s, \W, \w, and some of the POSIX character classes, as
- described for the PCRE2_UCP option below. In particular, it prevents
- the creator of the pattern from enabling this facility by starting the
- pattern with (*UCP). This option may be useful in applications that
- process patterns from external sources. The option combination
+ described for the PCRE2_UCP option below. In particular, it prevents
+ the creator of the pattern from enabling this facility by starting the
+ pattern with (*UCP). This option may be useful in applications that
+ process patterns from external sources. The option combination
PCRE2_UCP and PCRE2_NEVER_UCP causes an error.
PCRE2_NEVER_UTF
- This option locks out interpretation of the pattern as UTF-8, UTF-16,
+ This option locks out interpretation of the pattern as UTF-8, UTF-16,
or UTF-32, depending on which library is in use. In particular, it pre-
- vents the creator of the pattern from switching to UTF interpretation
- by starting the pattern with (*UTF). This option may be useful in ap-
+ vents the creator of the pattern from switching to UTF interpretation
+ by starting the pattern with (*UTF). This option may be useful in ap-
plications that process patterns from external sources. The combination
of PCRE2_UTF and PCRE2_NEVER_UTF causes an error.
PCRE2_NO_AUTO_CAPTURE
If this option is set, it disables the use of numbered capturing paren-
- theses in the pattern. Any opening parenthesis that is not followed by
- ? behaves as if it were followed by ?: but named parentheses can still
+ theses in the pattern. Any opening parenthesis that is not followed by
+ ? behaves as if it were followed by ?: but named parentheses can still
be used for capturing (and they acquire numbers in the usual way). This
- is the same as Perl's /n option. Note that, when this option is set,
- references to capture groups (backreferences or recursion/subroutine
- calls) may only refer to named groups, though the reference can be by
+ is the same as Perl's /n option. Note that, when this option is set,
+ references to capture groups (backreferences or recursion/subroutine
+ calls) may only refer to named groups, though the reference can be by
name or by number.
PCRE2_NO_AUTO_POSSESS
- If this (deprecated) option is set, it disables "auto-possessifica-
- tion", which is an optimization that, for example, turns a+b into a++b
+ If this (deprecated) option is set, it disables "auto-possessifica-
+ tion", which is an optimization that, for example, turns a+b into a++b
in order to avoid backtracks into a+ that can never be successful. How-
- ever, if callouts are in use, auto-possessification means that some
- callouts are never taken. You can set this option if you want the
- matching functions to do a full unoptimized search and run all the
+ ever, if callouts are in use, auto-possessification means that some
+ callouts are never taken. You can set this option if you want the
+ matching functions to do a full unoptimized search and run all the
callouts, but it is mainly provided for testing purposes.
- If a compile context is available, it is recommended to use
- pcre2_set_optimize() with the directive PCRE2_AUTO_POSSESS_OFF rather
- than the compile option PCRE2_NO_AUTO_POSSESS. Note that
- PCRE2_NO_AUTO_POSSESS takes precedence over the pcre2_set_optimize()
+ If a compile context is available, it is recommended to use
+ pcre2_set_optimize() with the directive PCRE2_AUTO_POSSESS_OFF rather
+ than the compile option PCRE2_NO_AUTO_POSSESS. Note that
+ PCRE2_NO_AUTO_POSSESS takes precedence over the pcre2_set_optimize()
optimization directives PCRE2_AUTO_POSSESS and PCRE2_AUTO_POSSESS_OFF.
PCRE2_NO_DOTSTAR_ANCHOR
If this (deprecated) option is set, it disables an optimization that is
- applied when .* is the first significant item in a top-level branch of
- a pattern, and all the other branches also start with .* or with \A or
+ applied when .* is the first significant item in a top-level branch of
+ a pattern, and all the other branches also start with .* or with \A or
\G or ^. The optimization is automatically disabled for .* if it is in-
- side an atomic group or a capture group that is the subject of a back-
+ side an atomic group or a capture group that is the subject of a back-
reference, or if the pattern contains (*PRUNE) or (*SKIP). When the op-
timization is not disabled, such a pattern is automatically anchored if
PCRE2_DOTALL is set for all the .* items and PCRE2_MULTILINE is not set
- for any ^ items. Otherwise, the fact that any match must start either
- at the start of the subject or following a newline is remembered. Like
+ for any ^ items. Otherwise, the fact that any match must start either
+ at the start of the subject or following a newline is remembered. Like
other optimizations, this can cause callouts to be skipped. (If a com-
- pile context is available, it is recommended to use pcre2_set_opti-
+ pile context is available, it is recommended to use pcre2_set_opti-
mize() with the directive PCRE2_DOTSTAR_ANCHOR_OFF instead.)
PCRE2_NO_START_OPTIMIZE
- This is an option whose main effect is at matching time. It does not
+ This is an option whose main effect is at matching time. It does not
change what pcre2_compile() generates, but it does affect the output of
the JIT compiler. Setting this option is equivalent to calling
- pcre2_set_optimize() with the directive parameter set to
+ pcre2_set_optimize() with the directive parameter set to
PCRE2_START_OPTIMIZE_OFF.
- There are a number of optimizations that may occur at the start of a
- match, in order to speed up the process. For example, if it is known
- that an unanchored match must start with a specific code unit value,
- the matching code searches the subject for that value, and fails imme-
- diately if it cannot find it, without actually running the main match-
- ing function. The start-up optimizations are in effect a pre-scan of
+ There are a number of optimizations that may occur at the start of a
+ match, in order to speed up the process. For example, if it is known
+ that an unanchored match must start with a specific code unit value,
+ the matching code searches the subject for that value, and fails imme-
+ diately if it cannot find it, without actually running the main match-
+ ing function. The start-up optimizations are in effect a pre-scan of
the subject that takes place before the pattern is run.
- Disabling the start-up optimizations may cause performance to suffer.
- However, this may be desirable for patterns which contain callouts or
- items such as (*COMMIT) and (*MARK). See the above description of
+ Disabling the start-up optimizations may cause performance to suffer.
+ However, this may be desirable for patterns which contain callouts or
+ items such as (*COMMIT) and (*MARK). See the above description of
PCRE2_START_OPTIMIZE_OFF for further details.
PCRE2_NO_UTF_CHECK
- When PCRE2_UTF is set, the validity of the pattern as a UTF string is
- automatically checked. There are discussions about the validity of
- UTF-8 strings, UTF-16 strings, and UTF-32 strings in the pcre2unicode
- document. If an invalid UTF sequence is found, pcre2_compile() returns
+ When PCRE2_UTF is set, the validity of the pattern as a UTF string is
+ automatically checked. There are discussions about the validity of
+ UTF-8 strings, UTF-16 strings, and UTF-32 strings in the pcre2unicode
+ document. If an invalid UTF sequence is found, pcre2_compile() returns
a negative error code.
- If you know that your pattern is a valid UTF string, and you want to
- skip this check for performance reasons, you can set the
+ If you know that your pattern is a valid UTF string, and you want to
+ skip this check for performance reasons, you can set the
PCRE2_NO_UTF_CHECK option. When it is set, the effect of passing an in-
- valid UTF string as a pattern is undefined. It may cause your program
+ valid UTF string as a pattern is undefined. It may cause your program
to crash or loop.
Note that this option can also be passed to pcre2_match() and
- pcre2_dfa_match(), to suppress UTF validity checking of the subject
+ pcre2_dfa_match(), to suppress UTF validity checking of the subject
string.
Note also that setting PCRE2_NO_UTF_CHECK at compile time does not dis-
- able the error that is given if an escape sequence for an invalid Uni-
- code code point is encountered in the pattern. In particular, the so-
- called "surrogate" code points (0xd800 to 0xdfff) are invalid. If you
- want to allow escape sequences such as \x{d800} you can set the
- PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES extra option, as described in the
- section entitled "Extra compile options" below. However, this is pos-
+ able the error that is given if an escape sequence for an invalid Uni-
+ code code point is encountered in the pattern. In particular, the so-
+ called "surrogate" code points (0xd800 to 0xdfff) are invalid. If you
+ want to allow escape sequences such as \x{d800} you can set the
+ PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES extra option, as described in the
+ section entitled "Extra compile options" below. However, this is pos-
sible only in UTF-8 and UTF-32 modes, because these values are not rep-
resentable in UTF-16.
PCRE2_UCP
This option has two effects. Firstly, it change the way PCRE2 processes
- \B, \b, \D, \d, \S, \s, \W, \w, and some of the POSIX character
- classes. By default, only ASCII characters are recognized, but if
- PCRE2_UCP is set, Unicode properties are used to classify characters.
- There are some PCRE2_EXTRA options (see below) that add finer control
- to this behaviour. More details are given in the section on generic
+ \B, \b, \D, \d, \S, \s, \W, \w, and some of the POSIX character
+ classes. By default, only ASCII characters are recognized, but if
+ PCRE2_UCP is set, Unicode properties are used to classify characters.
+ There are some PCRE2_EXTRA options (see below) that add finer control
+ to this behaviour. More details are given in the section on generic
character types in the pcre2pattern page.
- The second effect of PCRE2_UCP is to force the use of Unicode proper-
+ The second effect of PCRE2_UCP is to force the use of Unicode proper-
ties for upper/lower casing operations, even when PCRE2_UTF is not set.
- This makes it possible to process strings in the 16-bit UCS-2 code.
- This option is available only if PCRE2 has been compiled with Unicode
+ This makes it possible to process strings in the 16-bit UCS-2 code.
+ This option is available only if PCRE2 has been compiled with Unicode
support (which is the default).
The PCRE2_EXTRA_CASELESS_RESTRICT option (see above) restricts caseless
- matching such that ASCII characters match only ASCII characters and
- non-ASCII characters match only non-ASCII characters. The PCRE2_EX-
- TRA_TURKISH_CASING option (see above) alters the matching of the 'i'
- characters to follow their behaviour in Turkish and Azeri languages.
- For further details on PCRE2_EXTRA_CASELESS_RESTRICT and PCRE2_EX-
+ matching such that ASCII characters match only ASCII characters and
+ non-ASCII characters match only non-ASCII characters. The PCRE2_EX-
+ TRA_TURKISH_CASING option (see above) alters the matching of the 'i'
+ characters to follow their behaviour in Turkish and Azeri languages.
+ For further details on PCRE2_EXTRA_CASELESS_RESTRICT and PCRE2_EX-
TRA_TURKISH_CASING, see the pcre2unicode page.
PCRE2_UNGREEDY
- This option inverts the "greediness" of the quantifiers so that they
- are not greedy by default, but become greedy if followed by "?". It is
- not compatible with Perl. It can also be set by a (?U) option setting
+ This option inverts the "greediness" of the quantifiers so that they
+ are not greedy by default, but become greedy if followed by "?". It is
+ not compatible with Perl. It can also be set by a (?U) option setting
within the pattern.
PCRE2_USE_OFFSET_LIMIT
This option must be set for pcre2_compile() if pcre2_set_offset_limit()
- is going to be used to set a non-default offset limit in a match con-
- text for matches that use this pattern. An error is generated if an
- offset limit is set without this option. For more details, see the de-
- scription of pcre2_set_offset_limit() in the section that describes
+ is going to be used to set a non-default offset limit in a match con-
+ text for matches that use this pattern. An error is generated if an
+ offset limit is set without this option. For more details, see the de-
+ scription of pcre2_set_offset_limit() in the section that describes
match contexts. See also the PCRE2_FIRSTLINE option above.
PCRE2_UTF
- This option causes PCRE2 to regard both the pattern and the subject
- strings that are subsequently processed as strings of UTF characters
- instead of single-code-unit strings. It is available when PCRE2 is
- built to include Unicode support (which is the default). If Unicode
+ This option causes PCRE2 to regard both the pattern and the subject
+ strings that are subsequently processed as strings of UTF characters
+ instead of single-code-unit strings. It is available when PCRE2 is
+ built to include Unicode support (which is the default). If Unicode
support is not available, the use of this option provokes an error. De-
- tails of how PCRE2_UTF changes the behaviour of PCRE2 are given in the
+ tails of how PCRE2_UTF changes the behaviour of PCRE2 are given in the
pcre2unicode page. In particular, note that it changes the way
PCRE2_CASELESS works.
Extra compile options
- The option bits that can be set in a compile context by calling the
+ The option bits that can be set in a compile context by calling the
pcre2_set_compile_extra_options() function are as follows:
PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK
@@ -2070,158 +2080,158 @@ COMPILING A PATTERN
PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES
- This option applies when compiling a pattern in UTF-8 or UTF-32 mode.
- It is forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode
+ This option applies when compiling a pattern in UTF-8 or UTF-32 mode.
+ It is forbidden in UTF-16 mode, and ignored in non-UTF modes. Unicode
"surrogate" code points in the range 0xd800 to 0xdfff are used in pairs
- in UTF-16 to encode code points with values in the range 0x10000 to
- 0x10ffff. The surrogates cannot therefore be represented in UTF-16.
+ in UTF-16 to encode code points with values in the range 0x10000 to
+ 0x10ffff. The surrogates cannot therefore be represented in UTF-16.
They can be represented in UTF-8 and UTF-32, but are defined as invalid
- code points, and cause errors if encountered in a UTF-8 or UTF-32
+ code points, and cause errors if encountered in a UTF-8 or UTF-32
string that is being checked for validity by PCRE2.
- These values also cause errors if encountered in escape sequences such
+ These values also cause errors if encountered in escape sequences such
as \x{d912} within a pattern. However, it seems that some applications,
when using PCRE2 to check for unwanted characters in UTF-8 strings, ex-
- plicitly test for the surrogates using escape sequences. The
- PCRE2_NO_UTF_CHECK option does not disable the error that occurs, be-
+ plicitly test for the surrogates using escape sequences. The
+ PCRE2_NO_UTF_CHECK option does not disable the error that occurs, be-
cause it applies only to the testing of input strings for UTF validity.
- If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set, surro-
- gate code point values in UTF-8 and UTF-32 patterns no longer provoke
- errors and are incorporated in the compiled pattern. However, they can
- only match subject characters if the matching function is called with
+ If the extra option PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES is set, surro-
+ gate code point values in UTF-8 and UTF-32 patterns no longer provoke
+ errors and are incorporated in the compiled pattern. However, they can
+ only match subject characters if the matching function is called with
PCRE2_NO_UTF_CHECK set.
PCRE2_EXTRA_ALT_BSUX
- The original option PCRE2_ALT_BSUX causes PCRE2 to process \U, \u, and
- \x in the way that ECMAscript (aka JavaScript) does. Additional func-
+ The original option PCRE2_ALT_BSUX causes PCRE2 to process \U, \u, and
+ \x in the way that ECMAscript (aka JavaScript) does. Additional func-
tionality was defined by ECMAscript 6; setting PCRE2_EXTRA_ALT_BSUX has
- the effect of PCRE2_ALT_BSUX, but in addition it recognizes \u{hhh..}
+ the effect of PCRE2_ALT_BSUX, but in addition it recognizes \u{hhh..}
as a hexadecimal character code, where hhh.. is any number of hexadeci-
mal digits.
PCRE2_EXTRA_ASCII_BSD
- This option forces \d to match only ASCII digits, even when PCRE2_UCP
- is set. It can be changed within a pattern by means of the (?aD) op-
+ This option forces \d to match only ASCII digits, even when PCRE2_UCP
+ is set. It can be changed within a pattern by means of the (?aD) op-
tion setting.
PCRE2_EXTRA_ASCII_BSS
- This option forces \s to match only ASCII space characters, even when
- PCRE2_UCP is set. It can be changed within a pattern by means of the
+ This option forces \s to match only ASCII space characters, even when
+ PCRE2_UCP is set. It can be changed within a pattern by means of the
(?aS) option setting.
PCRE2_EXTRA_ASCII_BSW
- This option forces \w to match only ASCII word characters, even when
- PCRE2_UCP is set. It can be changed within a pattern by means of the
+ This option forces \w to match only ASCII word characters, even when
+ PCRE2_UCP is set. It can be changed within a pattern by means of the
(?aW) option setting.
PCRE2_EXTRA_ASCII_DIGIT
This option forces the POSIX character classes [:digit:] and [:xdigit:]
- to match only ASCII digits, even when PCRE2_UCP is set. It can be
+ to match only ASCII digits, even when PCRE2_UCP is set. It can be
changed within a pattern by means of the (?aT) option setting.
PCRE2_EXTRA_ASCII_POSIX
This option forces all the POSIX character classes, including [:digit:]
- and [:xdigit:], to match only ASCII characters, even when PCRE2_UCP is
- set. It can be changed within a pattern by means of the (?aP) option
- setting, but note that this also sets PCRE2_EXTRA_ASCII_DIGIT in order
+ and [:xdigit:], to match only ASCII characters, even when PCRE2_UCP is
+ set. It can be changed within a pattern by means of the (?aP) option
+ setting, but note that this also sets PCRE2_EXTRA_ASCII_DIGIT in order
to ensure that (?-aP) unsets all ASCII restrictions for POSIX classes.
PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL
- This is a dangerous option. Use with care. By default, an unrecognized
- escape such as \j or a malformed one such as \x{2z} causes a compile-
+ This is a dangerous option. Use with care. By default, an unrecognized
+ escape such as \j or a malformed one such as \x{2z} causes a compile-
time error when detected by pcre2_compile(). Perl is somewhat inconsis-
- tent in handling such items: for example, \j is treated as a literal
- "j", and non-hexadecimal digits in \x{} are just ignored, though warn-
- ings are given in both cases if Perl's warning switch is enabled. How-
- ever, a malformed octal number after \o{ always causes an error in
+ tent in handling such items: for example, \j is treated as a literal
+ "j", and non-hexadecimal digits in \x{} are just ignored, though warn-
+ ings are given in both cases if Perl's warning switch is enabled. How-
+ ever, a malformed octal number after \o{ always causes an error in
Perl.
- If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL extra option is passed to
- pcre2_compile(), all unrecognized or malformed escape sequences are
- treated as single-character escapes. For example, \j is a literal "j"
- and \x{2z} is treated as the literal string "x{2z}". Setting this op-
+ If the PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL extra option is passed to
+ pcre2_compile(), all unrecognized or malformed escape sequences are
+ treated as single-character escapes. For example, \j is a literal "j"
+ and \x{2z} is treated as the literal string "x{2z}". Setting this op-
tion means that typos in patterns may go undetected and have unexpected
- results. Also note that a sequence such as [\N{] is interpreted as a
- malformed attempt at [\N{...}] and so is treated as [N{] whereas [\N]
+ results. Also note that a sequence such as [\N{] is interpreted as a
+ malformed attempt at [\N{...}] and so is treated as [N{] whereas [\N]
gives an error because an unqualified \N is a valid escape sequence but
- is not supported in a character class. To reiterate: this is a danger-
+ is not supported in a character class. To reiterate: this is a danger-
ous option. Use with great care.
PCRE2_EXTRA_CASELESS_RESTRICT
- When either PCRE2_UCP or PCRE2_UTF is set, caseless matching follows
+ When either PCRE2_UCP or PCRE2_UTF is set, caseless matching follows
Unicode rules, which allow for more than two cases per character. There
are two case-equivalent character sets that contain both ASCII and non-
ASCII characters. The ASCII letter S is case-equivalent to U+017f (long
- S) and the ASCII letter K is case-equivalent to U+212a (Kelvin sign).
- This option disables recognition of case-equivalences that cross the
+ S) and the ASCII letter K is case-equivalent to U+212a (Kelvin sign).
+ This option disables recognition of case-equivalences that cross the
ASCII/non-ASCII boundary. In a caseless match, both characters must ei-
- ther be ASCII or non-ASCII. The option can be changed within a pattern
+ ther be ASCII or non-ASCII. The option can be changed within a pattern
by the (*CASELESS_RESTRICT) or (?r) option settings.
PCRE2_EXTRA_ESCAPED_CR_IS_LF
- There are some legacy applications where the escape sequence \r in a
- pattern is expected to match a newline. If this option is set, \r in a
- pattern is converted to \n so that it matches a LF (linefeed) instead
- of a CR (carriage return) character. The option does not affect a lit-
- eral CR in the pattern, nor does it affect CR specified as an explicit
+ There are some legacy applications where the escape sequence \r in a
+ pattern is expected to match a newline. If this option is set, \r in a
+ pattern is converted to \n so that it matches a LF (linefeed) instead
+ of a CR (carriage return) character. The option does not affect a lit-
+ eral CR in the pattern, nor does it affect CR specified as an explicit
code point such as \x{0D}.
PCRE2_EXTRA_MATCH_LINE
- This option is provided for use by the -x option of pcre2grep. It
- causes the pattern only to match complete lines. This is achieved by
- automatically inserting the code for "^(?:" at the start of the com-
- piled pattern and ")$" at the end. Thus, when PCRE2_MULTILINE is set,
- the matched line may be in the middle of the subject string. This op-
+ This option is provided for use by the -x option of pcre2grep. It
+ causes the pattern only to match complete lines. This is achieved by
+ automatically inserting the code for "^(?:" at the start of the com-
+ piled pattern and ")$" at the end. Thus, when PCRE2_MULTILINE is set,
+ the matched line may be in the middle of the subject string. This op-
tion can be used with PCRE2_LITERAL.
PCRE2_EXTRA_MATCH_WORD
- This option is provided for use by the -w option of pcre2grep. It
- causes the pattern only to match strings that have a word boundary at
- the start and the end. This is achieved by automatically inserting the
- code for "\b(?:" at the start of the compiled pattern and ")\b" at the
- end. The option may be used with PCRE2_LITERAL. However, it is ignored
+ This option is provided for use by the -w option of pcre2grep. It
+ causes the pattern only to match strings that have a word boundary at
+ the start and the end. This is achieved by automatically inserting the
+ code for "\b(?:" at the start of the compiled pattern and ")\b" at the
+ end. The option may be used with PCRE2_LITERAL. However, it is ignored
if PCRE2_EXTRA_MATCH_LINE is also set.
PCRE2_EXTRA_NO_BS0
If this option is set (note that its final character is the digit 0) it
- locks out the use of the sequence \0 unless at least one more octal
+ locks out the use of the sequence \0 unless at least one more octal
digit follows.
PCRE2_EXTRA_PYTHON_OCTAL
- If this option is set, PCRE2 follows Python's rules for interpreting
- octal escape sequences. The rules for handling sequences such as \14,
- which could be an octal number or a back reference are different. De-
+ If this option is set, PCRE2 follows Python's rules for interpreting
+ octal escape sequences. The rules for handling sequences such as \14,
+ which could be an octal number or a back reference are different. De-
tails are given in the pcre2pattern documentation.
PCRE2_EXTRA_NEVER_CALLOUT
If this option is set, PCRE2 treats callouts in the pattern as a syntax
error, returning PCRE2_ERROR_CALLOUT_CALLER_DISABLED. This is useful if
- the application knows that a callout will not be provided to
- pcre2_match(), so that callouts in the pattern are not silently ig-
+ the application knows that a callout will not be provided to
+ pcre2_match(), so that callouts in the pattern are not silently ig-
nored.
PCRE2_EXTRA_TURKISH_CASING
- This option alters case-equivalence of the 'i' letters to follow the
+ This option alters case-equivalence of the 'i' letters to follow the
alphabet used by Turkish and Azeri languages. The option can be changed
within a pattern by the (*TURKISH_CASING) start-of-pattern setting. Ei-
ther the UTF or UCP options must be set. In the 8-bit library, UTF must
- be set. This option cannot be combined with PCRE2_EXTRA_CASELESS_RE-
+ be set. This option cannot be combined with PCRE2_EXTRA_CASELESS_RE-
STRICT.
@@ -2244,16 +2254,16 @@ JUST-IN-TIME (JIT) COMPILATION
void pcre2_jit_stack_free(pcre2_jit_stack *jit_stack);
- These functions provide support for JIT compilation, which, if the
- just-in-time compiler is available, further processes a compiled pat-
+ These functions provide support for JIT compilation, which, if the
+ just-in-time compiler is available, further processes a compiled pat-
tern into machine code that executes much faster than the pcre2_match()
- interpretive matching function. Full details are given in the pcre2jit
+ interpretive matching function. Full details are given in the pcre2jit
documentation.
- JIT compilation is a heavyweight optimization. It can take some time
- for patterns to be analyzed, and for one-off matches and simple pat-
- terns the benefit of faster execution might be offset by a much slower
- compilation time. Most (but not all) patterns can be optimized by the
+ JIT compilation is a heavyweight optimization. It can take some time
+ for patterns to be analyzed, and for one-off matches and simple pat-
+ terns the benefit of faster execution might be offset by a much slower
+ compilation time. Most (but not all) patterns can be optimized by the
JIT compiler.
@@ -2264,48 +2274,48 @@ LOCALE SUPPORT
void pcre2_maketables_free(pcre2_general_context *gcontext,
const uint8_t *tables);
- PCRE2 handles caseless matching, and determines whether characters are
- letters, digits, or whatever, by reference to a set of tables, indexed
+ PCRE2 handles caseless matching, and determines whether characters are
+ letters, digits, or whatever, by reference to a set of tables, indexed
by character code point. However, this applies only to characters whose
- code points are less than 256. By default, higher-valued code points
+ code points are less than 256. By default, higher-valued code points
never match escapes such as \w or \d.
When PCRE2 is built with Unicode support (the default), certain Unicode
- character properties can be tested with \p and \P, or, alternatively,
+ character properties can be tested with \p and \P, or, alternatively,
the PCRE2_UCP option can be set when a pattern is compiled; this causes
- \w and friends to use Unicode property support instead of the built-in
+ \w and friends to use Unicode property support instead of the built-in
tables. PCRE2_UCP also causes upper/lower casing operations on charac-
ters with code points greater than 127 to use Unicode properties. These
- effects apply even when PCRE2_UTF is not set. There are, however, some
- PCRE2_EXTRA options (see above) that can be used to modify or suppress
+ effects apply even when PCRE2_UTF is not set. There are, however, some
+ PCRE2_EXTRA options (see above) that can be used to modify or suppress
them.
- The use of locales with Unicode is discouraged. If you are handling
- characters with code points greater than 127, you should either use
+ The use of locales with Unicode is discouraged. If you are handling
+ characters with code points greater than 127, you should either use
Unicode support, or use locales, but not try to mix the two.
- PCRE2 contains a built-in set of character tables that are used by de-
- fault. These are sufficient for many applications. Normally, the in-
- ternal tables recognize only ASCII characters. However, when PCRE2 is
+ PCRE2 contains a built-in set of character tables that are used by de-
+ fault. These are sufficient for many applications. Normally, the in-
+ ternal tables recognize only ASCII characters. However, when PCRE2 is
built, it is possible to cause the internal tables to be rebuilt in the
default "C" locale of the local system, which may cause them to be dif-
ferent.
- The built-in tables can be overridden by tables supplied by the appli-
- cation that calls PCRE2. These may be created in a different locale
- from the default. As more and more applications change to using Uni-
+ The built-in tables can be overridden by tables supplied by the appli-
+ cation that calls PCRE2. These may be created in a different locale
+ from the default. As more and more applications change to using Uni-
code, the need for this locale support is expected to die away.
- External tables are built by calling the pcre2_maketables() function,
+ External tables are built by calling the pcre2_maketables() function,
in the relevant locale. The only argument to this function is a general
- context, which can be used to pass a custom memory allocator. If the
+ context, which can be used to pass a custom memory allocator. If the
argument is NULL, the system malloc() is used. The result can be passed
to pcre2_compile() as often as necessary, by creating a compile context
- and calling pcre2_set_character_tables() to set the tables pointer
+ and calling pcre2_set_character_tables() to set the tables pointer
therein.
- For example, to build and use tables that are appropriate for the
- French locale (where accented characters with values greater than 127
+ For example, to build and use tables that are appropriate for the
+ French locale (where accented characters with values greater than 127
are treated as letters), the following code could be used:
setlocale(LC_CTYPE, "fr_FR");
@@ -2314,31 +2324,31 @@ LOCALE SUPPORT
pcre2_set_character_tables(ccontext, tables);
re = pcre2_compile(..., ccontext);
- The locale name "fr_FR" is used on Linux and other Unix-like systems;
+ The locale name "fr_FR" is used on Linux and other Unix-like systems;
if you are using Windows, the name for the French locale is "french".
The pointer that is passed (via the compile context) to pcre2_compile()
is saved with the compiled pattern, and the same tables are used by the
- matching functions. Thus, for any single pattern, compilation and
- matching both happen in the same locale, but different patterns can be
+ matching functions. Thus, for any single pattern, compilation and
+ matching both happen in the same locale, but different patterns can be
processed in different locales.
- It is the caller's responsibility to ensure that the memory containing
+ It is the caller's responsibility to ensure that the memory containing
the tables remains available while they are still in use. When they are
- no longer needed, you can discard them using pcre2_maketables_free(),
- which should pass as its first parameter the same global context that
+ no longer needed, you can discard them using pcre2_maketables_free(),
+ which should pass as its first parameter the same global context that
was used to create the tables.
Saving locale tables
- The tables described above are just a sequence of binary bytes, which
- makes them independent of hardware characteristics such as endianness
- or whether the processor is 32-bit or 64-bit. A copy of the result of
- pcre2_maketables() can therefore be saved in a file or elsewhere and
- re-used later, even in a different program or on another computer. The
- size of the tables (number of bytes) must be obtained by calling
- pcre2_config() with the PCRE2_CONFIG_TABLES_LENGTH option because
- pcre2_maketables() does not return this value. Note that the
+ The tables described above are just a sequence of binary bytes, which
+ makes them independent of hardware characteristics such as endianness
+ or whether the processor is 32-bit or 64-bit. A copy of the result of
+ pcre2_maketables() can therefore be saved in a file or elsewhere and
+ re-used later, even in a different program or on another computer. The
+ size of the tables (number of bytes) must be obtained by calling
+ pcre2_config() with the PCRE2_CONFIG_TABLES_LENGTH option because
+ pcre2_maketables() does not return this value. Note that the
pcre2_dftables program, which is part of the PCRE2 build system, can be
used stand-alone to create a file that contains a set of binary tables.
See the pcre2build documentation for details.
@@ -2348,13 +2358,13 @@ INFORMATION ABOUT A COMPILED PATTERN
int pcre2_pattern_info(const pcre2 *code, uint32_t what, void *where);
- The pcre2_pattern_info() function returns general information about a
+ The pcre2_pattern_info() function returns general information about a
compiled pattern. For information about callouts, see the next section.
- The first argument for pcre2_pattern_info() is a pointer to the com-
+ The first argument for pcre2_pattern_info() is a pointer to the com-
piled pattern. The second argument specifies which piece of information
- is required, and the third argument is a pointer to a variable to re-
- ceive the data. If the third argument is NULL, the first argument is
- ignored, and the function returns the size in bytes of the variable
+ is required, and the third argument is a pointer to a variable to re-
+ ceive the data. If the third argument is NULL, the first argument is
+ ignored, and the function returns the size in bytes of the variable
that is required for the information requested. Otherwise, the yield of
the function is zero for success, or one of the following negative num-
bers:
@@ -2365,8 +2375,8 @@ INFORMATION ABOUT A COMPILED PATTERN
PCRE2_ERROR_UNSET the requested field is not set
The "magic number" is placed at the start of each compiled pattern as a
- simple check against passing an arbitrary memory pointer. Here is a
- typical call of pcre2_pattern_info(), to obtain the length of the com-
+ simple check against passing an arbitrary memory pointer. Here is a
+ typical call of pcre2_pattern_info(), to obtain the length of the com-
piled pattern:
int rc;
@@ -2384,22 +2394,22 @@ INFORMATION ABOUT A COMPILED PATTERN
PCRE2_INFO_EXTRAOPTIONS
Return copies of the pattern's options. The third argument should point
- to a uint32_t variable. PCRE2_INFO_ARGOPTIONS returns exactly the op-
- tions that were passed to pcre2_compile(), whereas PCRE2_INFO_ALLOP-
- TIONS returns the compile options as modified by any top-level (*XXX)
- option settings such as (*UTF) at the start of the pattern itself.
- PCRE2_INFO_EXTRAOPTIONS returns the extra options that were set in the
- compile context by calling the pcre2_set_compile_extra_options() func-
+ to a uint32_t variable. PCRE2_INFO_ARGOPTIONS returns exactly the op-
+ tions that were passed to pcre2_compile(), whereas PCRE2_INFO_ALLOP-
+ TIONS returns the compile options as modified by any top-level (*XXX)
+ option settings such as (*UTF) at the start of the pattern itself.
+ PCRE2_INFO_EXTRAOPTIONS returns the extra options that were set in the
+ compile context by calling the pcre2_set_compile_extra_options() func-
tion.
- For example, if the pattern /(*UTF)abc/ is compiled with the PCRE2_EX-
- TENDED option, the result for PCRE2_INFO_ALLOPTIONS is PCRE2_EXTENDED
- and PCRE2_UTF. Option settings such as (?i) that can change within a
+ For example, if the pattern /(*UTF)abc/ is compiled with the PCRE2_EX-
+ TENDED option, the result for PCRE2_INFO_ALLOPTIONS is PCRE2_EXTENDED
+ and PCRE2_UTF. Option settings such as (?i) that can change within a
pattern do not affect the result of PCRE2_INFO_ALLOPTIONS, even if they
- appear right at the start of the pattern. (This was different in some
+ appear right at the start of the pattern. (This was different in some
earlier releases.)
- A pattern compiled without PCRE2_ANCHORED is automatically anchored by
+ A pattern compiled without PCRE2_ANCHORED is automatically anchored by
PCRE2 if the first significant item in every top-level branch is one of
the following:
@@ -2408,7 +2418,7 @@ INFORMATION ABOUT A COMPILED PATTERN
\G always
.* sometimes - see below
- When .* is the first significant item, anchoring is possible only when
+ When .* is the first significant item, anchoring is possible only when
all the following are true:
.* is not in an atomic group
@@ -2419,94 +2429,94 @@ INFORMATION ABOUT A COMPILED PATTERN
PCRE2_NO_DOTSTAR_ANCHOR is not set
Dotstar anchoring has not been disabled with PCRE2_DOTSTAR_ANCHOR_OFF
- For patterns that are auto-anchored, the PCRE2_ANCHORED bit is set in
+ For patterns that are auto-anchored, the PCRE2_ANCHORED bit is set in
the options returned for PCRE2_INFO_ALLOPTIONS.
PCRE2_INFO_BACKREFMAX
- Return the number of the highest backreference in the pattern. The
- third argument should point to a uint32_t variable. Named capture
- groups acquire numbers as well as names, and these count towards the
- highest backreference. Backreferences such as \4 or \g{12} match the
+ Return the number of the highest backreference in the pattern. The
+ third argument should point to a uint32_t variable. Named capture
+ groups acquire numbers as well as names, and these count towards the
+ highest backreference. Backreferences such as \4 or \g{12} match the
captured characters of the given group, but in addition, the check that
a capture group is set in a conditional group such as (?(3)a|b) is also
a backreference. Zero is returned if there are no backreferences.
PCRE2_INFO_BSR
- The output is a uint32_t integer whose value indicates what character
- sequences the \R escape sequence matches. A value of PCRE2_BSR_UNICODE
- means that \R matches any Unicode line ending sequence; a value of
+ The output is a uint32_t integer whose value indicates what character
+ sequences the \R escape sequence matches. A value of PCRE2_BSR_UNICODE
+ means that \R matches any Unicode line ending sequence; a value of
PCRE2_BSR_ANYCRLF means that \R matches only CR, LF, or CRLF.
PCRE2_INFO_CAPTURECOUNT
- Return the highest capture group number in the pattern. In patterns
+ Return the highest capture group number in the pattern. In patterns
where (?| is not used, this is also the total number of capture groups.
The third argument should point to a uint32_t variable.
PCRE2_INFO_DEPTHLIMIT
- If the pattern set a backtracking depth limit by including an item of
- the form (*LIMIT_DEPTH=nnnn) at the start, the value is returned. The
+ If the pattern set a backtracking depth limit by including an item of
+ the form (*LIMIT_DEPTH=nnnn) at the start, the value is returned. The
third argument should point to a uint32_t integer. If no such value has
- been set, the call to pcre2_pattern_info() returns the error PCRE2_ER-
+ been set, the call to pcre2_pattern_info() returns the error PCRE2_ER-
ROR_UNSET. Note that this limit will only be used during matching if it
- is less than the limit set or defaulted by the caller of the match
+ is less than the limit set or defaulted by the caller of the match
function.
PCRE2_INFO_FIRSTBITMAP
- In the absence of a single first code unit for a non-anchored pattern,
- pcre2_compile() may construct a 256-bit table that defines a fixed set
- of values for the first code unit in any match. For example, a pattern
- that starts with [abc] results in a table with three bits set. When
- code unit values greater than 255 are supported, the flag bit for 255
- means "any code unit of value 255 or above". If such a table was con-
- structed, a pointer to it is returned. Otherwise NULL is returned. The
+ In the absence of a single first code unit for a non-anchored pattern,
+ pcre2_compile() may construct a 256-bit table that defines a fixed set
+ of values for the first code unit in any match. For example, a pattern
+ that starts with [abc] results in a table with three bits set. When
+ code unit values greater than 255 are supported, the flag bit for 255
+ means "any code unit of value 255 or above". If such a table was con-
+ structed, a pointer to it is returned. Otherwise NULL is returned. The
third argument should point to a const uint8_t * variable.
PCRE2_INFO_FIRSTCODETYPE
Return information about the first code unit of any matched string, for
- a non-anchored pattern. The third argument should point to a uint32_t
- variable. If there is a fixed first value, for example, the letter "c"
- from a pattern such as (cat|cow|coyote), 1 is returned, and the value
- can be retrieved using PCRE2_INFO_FIRSTCODEUNIT. If there is no fixed
- first value, but it is known that a match can occur only at the start
- of the subject or following a newline in the subject, 2 is returned.
+ a non-anchored pattern. The third argument should point to a uint32_t
+ variable. If there is a fixed first value, for example, the letter "c"
+ from a pattern such as (cat|cow|coyote), 1 is returned, and the value
+ can be retrieved using PCRE2_INFO_FIRSTCODEUNIT. If there is no fixed
+ first value, but it is known that a match can occur only at the start
+ of the subject or following a newline in the subject, 2 is returned.
Otherwise, and for anchored patterns, 0 is returned.
PCRE2_INFO_FIRSTCODEUNIT
- Return the value of the first code unit of any matched string for a
- pattern where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise return 0.
- The third argument should point to a uint32_t variable. In the 8-bit
- library, the value is always less than 256. In the 16-bit library the
- value can be up to 0xffff. In the 32-bit library in UTF-32 mode the
+ Return the value of the first code unit of any matched string for a
+ pattern where PCRE2_INFO_FIRSTCODETYPE returns 1; otherwise return 0.
+ The third argument should point to a uint32_t variable. In the 8-bit
+ library, the value is always less than 256. In the 16-bit library the
+ value can be up to 0xffff. In the 32-bit library in UTF-32 mode the
value can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32
mode.
PCRE2_INFO_FRAMESIZE
Return the size (in bytes) of the data frames that are used to remember
- backtracking positions when the pattern is processed by pcre2_match()
- without the use of JIT. The third argument should point to a size_t
+ backtracking positions when the pattern is processed by pcre2_match()
+ without the use of JIT. The third argument should point to a size_t
variable. The frame size depends on the number of capturing parentheses
in the pattern. Each additional capture group adds two PCRE2_SIZE vari-
ables.
PCRE2_INFO_HASBACKSLASHC
- Return 1 if the pattern contains any instances of \C, otherwise 0. The
+ Return 1 if the pattern contains any instances of \C, otherwise 0. The
third argument should point to a uint32_t variable.
PCRE2_INFO_HASCRORLF
- Return 1 if the pattern contains any explicit matches for CR or LF
- characters, otherwise 0. The third argument should point to a uint32_t
- variable. An explicit match is either a literal CR or LF character, or
- \r or \n or one of the equivalent hexadecimal or octal escape se-
+ Return 1 if the pattern contains any explicit matches for CR or LF
+ characters, otherwise 0. The third argument should point to a uint32_t
+ variable. An explicit match is either a literal CR or LF character, or
+ \r or \n or one of the equivalent hexadecimal or octal escape se-
quences.
PCRE2_INFO_HEAPLIMIT
@@ -2514,45 +2524,45 @@ INFORMATION ABOUT A COMPILED PATTERN
If the pattern set a heap memory limit by including an item of the form
(*LIMIT_HEAP=nnnn) at the start, the value is returned. The third argu-
ment should point to a uint32_t integer. If no such value has been set,
- the call to pcre2_pattern_info() returns the error PCRE2_ERROR_UNSET.
- Note that this limit will only be used during matching if it is less
+ the call to pcre2_pattern_info() returns the error PCRE2_ERROR_UNSET.
+ Note that this limit will only be used during matching if it is less
than the limit set or defaulted by the caller of the match function.
PCRE2_INFO_JCHANGED
- Return 1 if the (?J) or (?-J) option setting is used in the pattern,
- otherwise 0. The third argument should point to a uint32_t variable.
- (?J) and (?-J) set and unset the local PCRE2_DUPNAMES option, respec-
+ Return 1 if the (?J) or (?-J) option setting is used in the pattern,
+ otherwise 0. The third argument should point to a uint32_t variable.
+ (?J) and (?-J) set and unset the local PCRE2_DUPNAMES option, respec-
tively.
PCRE2_INFO_JITSIZE
- If the compiled pattern was successfully processed by pcre2_jit_com-
- pile(), return the size of the JIT compiled code, otherwise return
+ If the compiled pattern was successfully processed by pcre2_jit_com-
+ pile(), return the size of the JIT compiled code, otherwise return
zero. The third argument should point to a size_t variable.
PCRE2_INFO_LASTCODETYPE
- Returns 1 if there is a rightmost literal code unit that must exist in
- any matched string, other than at its start. The third argument should
+ Returns 1 if there is a rightmost literal code unit that must exist in
+ any matched string, other than at its start. The third argument should
point to a uint32_t variable. If there is no such value, 0 is returned.
- When 1 is returned, the code unit value itself can be retrieved using
+ When 1 is returned, the code unit value itself can be retrieved using
PCRE2_INFO_LASTCODEUNIT. For anchored patterns, a last literal value is
- recorded only if it follows something of variable length. For example,
- for the pattern /^a\d+z\d+/ the returned value is 1 (with "z" returned
- from PCRE2_INFO_LASTCODEUNIT), but for /^a\dz\d/ the returned value is
+ recorded only if it follows something of variable length. For example,
+ for the pattern /^a\d+z\d+/ the returned value is 1 (with "z" returned
+ from PCRE2_INFO_LASTCODEUNIT), but for /^a\dz\d/ the returned value is
0.
PCRE2_INFO_LASTCODEUNIT
- Return the value of the rightmost literal code unit that must exist in
- any matched string, other than at its start, for a pattern where
+ Return the value of the rightmost literal code unit that must exist in
+ any matched string, other than at its start, for a pattern where
PCRE2_INFO_LASTCODETYPE returns 1. Otherwise, return 0. The third argu-
ment should point to a uint32_t variable.
PCRE2_INFO_MATCHEMPTY
- Return 1 if the pattern might match an empty string, otherwise 0. The
+ Return 1 if the pattern might match an empty string, otherwise 0. The
third argument should point to a uint32_t variable. When a pattern con-
tains recursive subroutine calls it is not always possible to determine
whether or not it can match an empty string. PCRE2 takes a cautious ap-
@@ -2560,44 +2570,44 @@ INFORMATION ABOUT A COMPILED PATTERN
PCRE2_INFO_MATCHLIMIT
- If the pattern set a match limit by including an item of the form
- (*LIMIT_MATCH=nnnn) at the start, the value is returned. The third ar-
- gument should point to a uint32_t integer. If no such value has been
+ If the pattern set a match limit by including an item of the form
+ (*LIMIT_MATCH=nnnn) at the start, the value is returned. The third ar-
+ gument should point to a uint32_t integer. If no such value has been
set, the call to pcre2_pattern_info() returns the error PCRE2_ERROR_UN-
- SET. Note that this limit will only be used during matching if it is
- less than the limit set or defaulted by the caller of the match func-
+ SET. Note that this limit will only be used during matching if it is
+ less than the limit set or defaulted by the caller of the match func-
tion.
PCRE2_INFO_MAXLOOKBEHIND
- A lookbehind assertion moves back a certain number of characters (not
- code units) when it starts to process each of its branches. This re-
- quest returns the largest of these backward moves. The third argument
+ A lookbehind assertion moves back a certain number of characters (not
+ code units) when it starts to process each of its branches. This re-
+ quest returns the largest of these backward moves. The third argument
should point to a uint32_t integer. The simple assertions \b and \B re-
- quire a one-character lookbehind and cause PCRE2_INFO_MAXLOOKBEHIND to
- return 1 in the absence of anything longer. \A also registers a one-
- character lookbehind, though it does not actually inspect the previous
+ quire a one-character lookbehind and cause PCRE2_INFO_MAXLOOKBEHIND to
+ return 1 in the absence of anything longer. \A also registers a one-
+ character lookbehind, though it does not actually inspect the previous
character.
Note that this information is useful for multi-segment matching only if
- the pattern contains no nested lookbehinds. For example, the pattern
- (?<=a(?<=ba)c) returns a maximum lookbehind of 2, but when it is
- processed, the first lookbehind moves back by two characters, matches
- one character, then the nested lookbehind also moves back by two char-
- acters. This puts the matching point three characters earlier than it
- was at the start. PCRE2_INFO_MAXLOOKBEHIND is really only useful as a
- debugging tool. See the pcre2partial documentation for a discussion of
+ the pattern contains no nested lookbehinds. For example, the pattern
+ (?<=a(?<=ba)c) returns a maximum lookbehind of 2, but when it is
+ processed, the first lookbehind moves back by two characters, matches
+ one character, then the nested lookbehind also moves back by two char-
+ acters. This puts the matching point three characters earlier than it
+ was at the start. PCRE2_INFO_MAXLOOKBEHIND is really only useful as a
+ debugging tool. See the pcre2partial documentation for a discussion of
multi-segment matching.
PCRE2_INFO_MINLENGTH
- If a minimum length for matching subject strings was computed, its
+ If a minimum length for matching subject strings was computed, its
value is returned. Otherwise the returned value is 0. This value is not
- computed when PCRE2_NO_START_OPTIMIZE is set. The value is a number of
- characters, which in UTF mode may be different from the number of code
- units. The third argument should point to a uint32_t variable. The
- value is a lower bound to the length of any matching string. There may
- not be any strings of that length that do actually match, but every
+ computed when PCRE2_NO_START_OPTIMIZE is set. The value is a number of
+ characters, which in UTF mode may be different from the number of code
+ units. The third argument should point to a uint32_t variable. The
+ value is a lower bound to the length of any matching string. There may
+ not be any strings of that length that do actually match, but every
string that does match is at least that long.
PCRE2_INFO_NAMECOUNT
@@ -2605,51 +2615,51 @@ INFORMATION ABOUT A COMPILED PATTERN
PCRE2_INFO_NAMETABLE
PCRE2 supports the use of named as well as numbered capturing parenthe-
- ses. The names are just an additional way of identifying the parenthe-
+ ses. The names are just an additional way of identifying the parenthe-
ses, which still acquire numbers. Several convenience functions such as
- pcre2_substring_get_byname() are provided for extracting captured sub-
- strings by name. It is also possible to extract the data directly, by
- first converting the name to a number in order to access the correct
- pointers in the output vector (described with pcre2_match() below). To
+ pcre2_substring_get_byname() are provided for extracting captured sub-
+ strings by name. It is also possible to extract the data directly, by
+ first converting the name to a number in order to access the correct
+ pointers in the output vector (described with pcre2_match() below). To
do the conversion, you need to use the name-to-number map, which is de-
scribed by these three values.
- The map consists of a number of fixed-size entries. PCRE2_INFO_NAME-
- COUNT gives the number of entries, and PCRE2_INFO_NAMEENTRYSIZE gives
- the size of each entry in code units; both of these return a uint32_t
+ The map consists of a number of fixed-size entries. PCRE2_INFO_NAME-
+ COUNT gives the number of entries, and PCRE2_INFO_NAMEENTRYSIZE gives
+ the size of each entry in code units; both of these return a uint32_t
value. The entry size depends on the length of the longest name.
PCRE2_INFO_NAMETABLE returns a pointer to the first entry of the table.
This is a PCRE2_SPTR pointer to a block of code units. In the 8-bit li-
- brary, the first two bytes of each entry are the number of the captur-
- ing parenthesis, most significant byte first. In the 16-bit library,
- the pointer points to 16-bit code units, the first of which contains
- the parenthesis number. In the 32-bit library, the pointer points to
- 32-bit code units, the first of which contains the parenthesis number.
+ brary, the first two bytes of each entry are the number of the captur-
+ ing parenthesis, most significant byte first. In the 16-bit library,
+ the pointer points to 16-bit code units, the first of which contains
+ the parenthesis number. In the 32-bit library, the pointer points to
+ 32-bit code units, the first of which contains the parenthesis number.
The rest of the entry is the corresponding name, zero terminated.
- The names are in alphabetical order. If (?| is used to create multiple
+ The names are in alphabetical order. If (?| is used to create multiple
capture groups with the same number, as described in the section on du-
plicate group numbers in the pcre2pattern page, the groups may be given
- the same name, but there is only one entry in the table. Different
+ the same name, but there is only one entry in the table. Different
names for groups of the same number are not permitted.
- Duplicate names for capture groups with different numbers are permit-
+ Duplicate names for capture groups with different numbers are permit-
ted, but only if PCRE2_DUPNAMES is set. They appear in the table in the
- order in which they were found in the pattern. In the absence of (?|
- this is the order of increasing number; when (?| is used this is not
- necessarily the case because later capture groups may have lower num-
+ order in which they were found in the pattern. In the absence of (?|
+ this is the order of increasing number; when (?| is used this is not
+ necessarily the case because later capture groups may have lower num-
bers.
- As a simple example of the name/number table, consider the following
- pattern after compilation by the 8-bit library (assume PCRE2_EXTENDED
+ As a simple example of the name/number table, consider the following
+ pattern after compilation by the 8-bit library (assume PCRE2_EXTENDED
is set, so white space - including newlines - is ignored):
(?